package com.ubs.lingua.buildtool.cs;

import com.healthmarketscience.rmiio.RemoteInputStream;
import com.ubs.lingua.buildtool.cs.parameters.BuildParameters;

/**
 * Public facade interface for the Lingua C# Build Agent.
 */
public interface CsBuilderFacade {

    /**
     * <p>Requests a new build batch to be started.
     * This method starts new build process and returns immediately its unique ID to the caller.
     * The actual execution of the build process will occur in a asynchronous task.</p>
     * <p>It is possible to monitor the build process using the {@link CsBuilderFacade#isBatchDone(String)} method.</p>
     * <p>Build result can be retrieved using the {@link CsBuilderFacade#getAssembly(String)} method.</p>
     * <p>The method caller should provide ZIP archive containing source code of .NET assembly which should be built
     * and all dependencies. This ZIP mast has the following structure:</p>
     * <pre>root.zip
     * |--lib
     * |   |--depAssembly1.dll
     * |  ...
     * |   `--depAssemblyN.dll
     * `--src
     *     `--UBS
     *         `--Lingua
     *              `--MyAssembly
     *                   |--SrcFile1.cs
     *                  ...
     *                   `--SrcFileM.cs</pre>
     * <p>It is also allowed to have one or more top level directories in the ZIP archive root:</p>
     * <pre>root.zip
     * `--myAssembly
     *      `--toBeBuilt
     *           |--lib
     *           |   `--...
     *           `--src
     *               `--...</pre>
     * @see com.ubs.lingua.buildtool.cs.parameters.BuildParameters
     * @param parameters the build batch parameters
     * @param sourcePackage RMIIO {@link RemoteInputStream} instance of the input ZIP archive
     * @return unique build batch ID
     * @throws Exception
     */
    String buildAssembly(BuildParameters parameters, RemoteInputStream sourcePackage) throws Exception;

    /**
     * <p>Returns ZIP archive containing assembly (or assemblies) for the build batch (build request).
     * This method makes calling thread wait if necessary for the build process to complete.</p>
     * <p>The returned ZIP archive has the following structure:</p>
     * <pre>root.zip
     *  |--Platform1
     *  |    |--DEBUG
     *  |    |    `--assembly.dll
     *  |    `--RELEASE
     *  |         `--assembly.dll
     *  |--Platform2
     *  |    |--DEBUG
     *  |    |    `--assembly.dll
     *  |    `--RELEASE
     *  |         `--assembly.dll
     * ...
     *  `--PlatformN
     *       |--DEBUG
     *       |    `--assembly.dll
     *       `--RELEASE
     *            `--assembly.dll</pre>
     * <p>Target platform(s) (X64, X86, ...) and configuration (DEBUG, RELEASE) is set as parameters when requesting a build batch.</p>
     * <p>The returned ZIP archive has the following structure if assembly for one platform and configuration only was requested
     * (let's consider X86 and Release were set when a build batch was requested):</p>
     * <pre>root.zip
     *  `--X86
     *      `--RELEASE
     *           `--assembly.dll</pre>
     * @see com.ubs.lingua.buildtool.cs.parameters.BuildParameters
     * @param batchId the build batch identifier
     * @return RMIIO {@link RemoteInputStream} instance of the output ZIP archive
     * @throws Exception when build was completed with exception
     */
    RemoteInputStream getAssembly(String batchId) throws Exception;

    /**
     * Returns true if the build batch (build request) is done.
     * Completion may be due to normal termination or exception -- in all of these cases, this method will return true.
     * @param batchId the build batch identifier
     * @return true if this build batch completed
     */
    boolean isBatchDone(String batchId);

    /**
     * <p>Returns the working repository path.
     * This path is set in the <code>csbuildagent.properties</code> configuration file.</p>
     * <p>Note: the path can be either absolute or relative to the Lingua C# Build Agent JAR.</p>
     * @return the working repository path
     */
    String getRepositoryPath();

    /**
     * Checks if the Lingua C# Build Agent is in debug mode.
     * @return whether the Lingua C# Build Agent is in debug mode
     */
    boolean isDebugMode();

    /**
     * Switch debug mode on/off.
     * Lingua C# Build Agent will retain all temporary files in the working repository to allow build problems investigation.
     * @param debugMode Lingua C# Build Agent mode. Debug mode is enabled by setting this parameter value to <code>true</code>.
     */
    void setDebugMode(boolean debugMode);

}
